home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / umsg.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  9KB  |  210 lines
  1. /*
  2. *******************************************************************************
  3. *                                                                             *
  4. * COPYRIGHT:                                                                  *
  5. *   (C) Copyright Taligent, Inc.,  1996                                       *
  6. *   (C) Copyright International Business Machines Corporation,  1998-1999     *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.        *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure   *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                    *
  10. *                                                                             *
  11. *******************************************************************************
  12. */
  13.  
  14. #ifndef UMSG_H
  15. #define UMSG_H
  16.  
  17. #include "utypes.h"
  18. #include <stdarg.h>
  19. /**
  20.  * Provides means to produce concatenated messages in language-neutral way.
  21.  * Use this for all concatenations that show up to end users.
  22.  * <P>
  23.  * Takes a set of objects, formats them, then inserts the formatted
  24.  * strings into the pattern at the appropriate places.
  25.  * <P>
  26.  * Here are some examples of usage:
  27.  * Example 1:
  28.  * <pre>
  29.  * .    UChar *result, *tzID, *str;
  30.  * .    UChar pattern[100];
  31.  * .    t_int32 resultLengthOut, resultlength;
  32.  * .    UCalendar *cal;
  33.  * .    UDate d1;
  34.  * .    UDateFormat *def1;
  35.  * .    UErrorCode status = U_ZERO_ERROR;
  36.  * .    str=(UChar*)malloc(sizeof(UChar) * (strlen("disturbance in force") +1));
  37.  * .    u_uastrcpy(str, "disturbance in force");
  38.  * .    tzID=(UChar*)malloc(sizeof(UChar) * 4);
  39.  * .    u_uastrcpy(tzID, "PST");
  40.  * .    cal=ucal_open(tzID, u_strlen(tzID), "en_US", UCAL_TRADITIONAL, &status);
  41.  * .    ucal_setDateTime(cal, 1999, UCAL_MARCH, 18, 0, 0, 0, &status);
  42.  * .    d1=ucal_getMillis(cal, &status);
  43.  * .    u_uastrcpy(pattern, "On {0, date, long}, there was a {1} on planet {2,number,integer}");
  44.  * .    resultlength=0;
  45.  * .    resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, d1, str, 7);
  46.  * .    if(status==U_BUFFER_OVERFLOW_ERROR){
  47.  * .        status=U_ZERO_ERROR;
  48.  * .        resultlength=resultLengthOut+1;
  49.  * .        result=(UChar*)realloc(result, sizeof(UChar) * resultlength);
  50.  * .        u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultlength, &status, d1, str, 7);
  51.  * .    }
  52.  * .    printf("%s\n", austrdup(result) );//austrdup( a function used to convert UChar* to char*)
  53.  * .    //output>: "On March 18, 1999, there was a disturbance in force on planet 7
  54.  * </pre>  
  55.  * Typically, the message format will come from resources, and the
  56.  * arguments will be dynamically set at runtime.
  57.  * <P>
  58.  * Example 2:
  59.  * <pre>
  60.  * .    UChar* str;
  61.  * .    UErrorCode status = U_ZERO_ERROR;
  62.  * .    UChar *result;
  63.  * .    UChar pattern[100];
  64.  * .    t_int32 resultlength,resultLengthOut, i;
  65.  * .    double testArgs= { 100.0, 1.0, 0.0};
  66.  * .    str=(UChar*)malloc(sizeof(UChar) * 10);
  67.  * .    u_uastrcpy(str, "MyDisk");
  68.  * .    u_uastrcpy(pattern, "The disk {1} contains {0,choice,0#no files|1#one file|1<{0,number,integer} files}");
  69.  * .    for(i=0; i<3; i++){
  70.  * .      resultlength=0;
  71.  * .    resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern), NULL, resultlength, &status, testArgs[i], str);
  72.  * .    if(status==U_BUFFER_OVERFLOW_ERROR){
  73.  * .        status=U_ZERO_ERROR;
  74.  * .        resultlength=resultLengthOut+1;
  75.  * .        result=(UChar*)malloc(sizeof(UChar) * resultlength);
  76.  * .        u_formatMessage( "en_US", pattern, u_strlen(pattern), result, resultlength, &status, testArgs[i], str);
  77.  * .    }
  78.  * .    printf("%s\n", austrdup(result) );  //austrdup( a function used to convert UChar* to char*)
  79.  * .    free(result);
  80.  * .    }
  81.  * .    // output, with different testArgs:
  82.  * .    // output: The disk "MyDisk" contains 100 files.
  83.  * .    // output: The disk "MyDisk" contains one file.
  84.  * .    // output: The disk "MyDisk" contains no files.
  85.  *  </pre>
  86.  *
  87.  *  The pattern is of the following form.  Legend:
  88.  *  <pre>
  89.  * .      {optional item}
  90.  * .      (group that may be repeated)*
  91.  *  </pre>
  92.  *  Do not confuse optional items with items inside quotes braces, such
  93.  *  as this: "{".  Quoted braces are literals.
  94.  *  <pre>
  95.  * .      messageFormatPattern := string ( "{" messageFormatElement "}" string )*
  96.  * .       
  97.  * .      messageFormatElement := argument { "," elementFormat }
  98.  * .       
  99.  * .      elementFormat := "time" { "," datetimeStyle }
  100.  * .                     | "date" { "," datetimeStyle }
  101.  * .                     | "number" { "," numberStyle }
  102.  * .                     | "choice" "," choiceStyle
  103.  * .  
  104.  * .      datetimeStyle := "short"
  105.  * .                     | "medium"
  106.  * .                     | "long"
  107.  * .                     | "full"
  108.  * .                     | dateFormatPattern
  109.  * .
  110.  * .      numberStyle :=   "currency"
  111.  * .                     | "percent"
  112.  * .                     | "integer"
  113.  * .                     | numberFormatPattern
  114.  * . 
  115.  * .      choiceStyle :=   choiceFormatPattern
  116.  * </pre>
  117.  * If there is no elementFormat, then the argument must be a string,
  118.  * which is substituted. If there is no dateTimeStyle or numberStyle,
  119.  * then the default format is used (e.g.  NumberFormat.getInstance(),
  120.  * DateFormat.getDefaultTime() or DateFormat.getDefaultDate(). For
  121.  * a ChoiceFormat, the pattern must always be specified, since there
  122.  * is no default.
  123.  * <P>
  124.  * In strings, single quotes can be used to quote the "{" sign if
  125.  * necessary. A real single quote is represented by ''.  Inside a
  126.  * messageFormatElement, quotes are [not] removed. For example,
  127.  * {1,number,$'#',##} will produce a number format with the pound-sign
  128.  * quoted, with a result such as: "$#31,45".
  129.  * <P>
  130.  * If a pattern is used, then unquoted braces in the pattern, if any,
  131.  * must match: that is, "ab {0} de" and "ab '}' de" are ok, but "ab
  132.  * {0'}' de" and "ab } de" are not.
  133.  * <P>
  134.  * The argument is a number from 0 to 9, which corresponds to the
  135.  * arguments presented in an array to be formatted.
  136.  * <P>
  137.  * It is ok to have unused arguments in the array.  With missing
  138.  * arguments or arguments that are not of the right class for the
  139.  * specified format, a failing UErrorCode result is set.
  140.  * <P>
  141.  
  142.  * <P>
  143.  * [Note:] As we see above, the string produced by a choice Format in
  144.  * MessageFormat is treated specially; occurances of '{' are used to
  145.  * indicated subformats.  
  146.  * <P>
  147.  * [Note:] Formats are numbered by order of variable in the string.
  148.  * This is [not] the same as the argument numbering!
  149.  * <pre>
  150.  * .   For example: with "abc{2}def{3}ghi{0}...",
  151.  * .   
  152.  * .   format0 affects the first variable {2}
  153.  * .   format1 affects the second variable {3}
  154.  * .   format2 affects the second variable {0}
  155.  * </pre>
  156.  * and so on.
  157.  */
  158.  
  159. /**
  160. * Format a message for a locale.
  161. * This function may perform re-ordering of the arguments depending on the
  162. * locale. For all numeric arguments, double is assumed unless the type is
  163. * explicitly integer.  All choice format arguments must be of type double.
  164. * @param locale The locale for which the message will be formatted
  165. * @param pattern The pattern specifying the message's format
  166. * @param patternLength The length of pattern
  167. * @param result A pointer to a buffer to receive the formatted message.
  168. * @param resultLength The maximum size of result.
  169. * @param status A pointer to an UErrorCode to receive any errors
  170. * @param ... A variable-length argument list containing the arguments specified
  171. * in pattern.
  172. * @return The total buffer size needed; if greater than resultLength, the 
  173. * output was truncated.
  174. * @see u_parseMessage
  175. */
  176. U_CAPI int32_t
  177. u_formatMessage(    const    char        *locale,
  178.             const    UChar        *pattern,
  179.                 int32_t        patternLength,
  180.                 UChar        *result,
  181.                 int32_t        resultLength,
  182.                 UErrorCode    *status,
  183.                 ...);
  184.  
  185. /**
  186. * Parse a message.
  187. * For numeric arguments, this function will always use doubles.  Integer types
  188. * should not be passed.  
  189. * This function is not able to parse all output from \Ref{u_formatMessage}.
  190. * @param locale The locale for which the message is formatted
  191. * @param pattern The pattern specifying the message's format
  192. * @param patternLength The length of pattern
  193. * @param source The text to parse.
  194. * @param sourceLength The length of source, or -1 if null-terminated.
  195. * @param status A pointer to an UErrorCode to receive any errors
  196. * @param ... A variable-length argument list containing the arguments
  197. * specified in pattern.
  198. * @see u_formatMessage
  199. */
  200. U_CAPI void 
  201. u_parseMessage(    const    char        *locale,
  202.         const    UChar        *pattern,
  203.             int32_t        patternLength,
  204.         const    UChar        *source,
  205.             int32_t        sourceLength,
  206.             UErrorCode    *status,
  207.             ...);
  208.  
  209. #endif
  210.